Release 10.1A: OpenEdge Development:
ADM and SmartObjects

Customizing the visual class

The example in this section illustrates customizing the visual class. The customization defines a special property that you can set to specify the background color for SmartObjects that inherit from this class (that is, all visual SmartObjects), thus standardizing the look of your Progress 4GL applications.

The following sections note which custom class files you need to provide, and describe how to modify them to create the new functionality.

Copying the visual custom class files

You customize an existing class by modifying the custom class files built into that class. For this example, you will modify a selected set of the visual custom class files. You work on a copy of the required files in your working directory rather than in their installed location.

To prepare for customization:

Copy the following files from the %DLC%\src\adm2\custom (Windows) or $DLC/src/adm2/custom (UNIX) directory into the src\adm2\custom (Windows) or src/adm2/custom directory under your working directory:

vispropcustom.i
visualcustom.p
visualdefscustom.i

Modifying the visual custom class files

You use the following new code to customize the visual class with the new functionality: a BgColor property, setBgColor and getBgColor functions, and an override procedure for the standard ADM initializeObject method. Adding this functionality requires changes to the visualcustom.i primary include file, the vispropcustom.i property file, the visualcustom.p super procedure file, and the visualdefscustom.i custom instance definition file, which you will copy and open as required.

To add the new functionality in the AppBuilder:

Define the BgColor property in the vispropcustom.i custom property file in your working directory). To do this, open the file, go to its main block, and add the code shown in bold typeface:

/* Include the file that defines prototypes for all of the super procedure’s entry points. And skip including the prototypes if we are *any* super procedure. */ &IF "{&ADMSuper}":U EQ "":U &THEN {src/adm2/custom/visprtocustom.i} &ENDIF &GLOB xpBgColor &IF "{&ADMSuper}":U = "":U &THEN ghADMProps:ADD-NEW-FIELD(’BgColor’:U, ’INTEGER’:U, 0, ?, 7). &ENDIF /* _UIB-CODE-BLOCK-END */ &ANALYZE-RESUME

When you finish making these changes, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the property file window.

Create new setBgColor and getBgColor functions in the visualcustom.p super procedure file. These functions allows you to set and get the new Bgcolor property publicly. To create the new functions, open the file, then add the code shown in bold typeface:

FUNCTION getBgColor RETURNS INTEGER ( /* parameter-definitions */ ) : /*------------------------------------------------------------------- Purpose: Notes: -------------------------------------------------------------------*/ DEFINE VARIABLE iBgColor AS INTEGER NO-UNDO. {get BgColor iBgColor}. RETURN iBgColor. /* Function return value. */ END FUNCTION. FUNCTION setBgColor RETURNS LOGICAL ( INPUT piBgColor AS INTEGER ) : /*------------------------------------------------------------------- Purpose: Notes: -------------------------------------------------------------------*/ {set BgColor piBgColor}. RETURN TRUE. /* Function return value. */ END FUNCTION.

Create an override procedure for the initializeObject method in the visualcustom.p custom super procedure file in your working directory. This procedure gets the current value of the new BgColor property and sets the background color of container frame accordingly. To create the new override procedure, add the code shown in bold typeface:

PROCEDURE initializeObject : /*--------------------------------------------------------------------- --------- Purpose: Parameters: <none> Notes: ----------------------------------------------------------------------- -----*/ DEFINE VARIABLE hFrame AS HANDLE NO-UNDO. DEFINE VARIABLE iBgColor AS INTEGER NO-UNDO. {get ContainerHandle hFrame}. {get BgColor iBgColor}. RUN SUPER. /* Don’t do anything in design mode */ IF DYNAMIC-FUNCTION (’getUIBMode’:U IN TARGET-PROCEDURE) NE "":U THEN RETURN. IF hFrame:TYPE = "FRAME":U THEN hFrame:BGCOLOR = iBgColor. ELSE IF hFrame:TYPE = "WINDOW":U THEN ASSIGN hFrame = hFrame:FIRST-CHILD hFrame:BGCOLOR = iBgColor. END PROCEDURE.

When you finish making the changes in Step 2 and Step 3, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the super procedure file window. The AppBuilder now creates a .r version of the super procedure in the src\adm2 directory under your working directory.

Edit the visualcustom.i primary include file, and uncomment the line that starts the custom super procedure. When you finish making this change, click on the Save button (the diskette icon) on the AppBuilder main window to save your change, then close the primary include file window.
Add the BgColor property to the list of instance properties, and specify a filename for the instance properties dialog in the visualdefscustom.i custom instance definition file in your working directory. To add the property and filename, open the file, then add the code shown in bold typeface:

/*--------------------------------------------------------------------- ----- File : visualdefscustom.i Purpose : Entry point to define: New definitions {&xcInstanceProperties} {&ADM-PROPERTY-DLG} Syntax : {src/adm2/custom/visualdefscustom.i} Modified : 06/03/1999 Notes : Referenced in {src/adm2/visprop.i} ----------------------------------------------------------------------- -*/ &IF "{&xcInstanceProperties}":U NE "":U &THEN &GLOB xcInstanceProperties {&xcInstanceProperties}, &ENDIF &GLOB xcInstanceProperties {&xcInstanceProperties} BgColor &GLOBAL-DEFINE ADM-PROPERTY-DLG adm2/support/myvisuald.w

You have specified adm2/support/visuald.w—that is, the file visuald.w in the adm2\support directory under your working directory—as the instance properties dialog box file. (Progress code is not sensitive to whether you use forward or reverse slashes in pathnames.) You will add support for this dialog box in the next step.

When you finish making these changes, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the property file window.

Provide support for your new property in the instance properties dialog box. In this example, the simplest approach is to copy the instance property dialog box for the visual class, visuald.w, from the %DLC%\src\adm2\support directory to src\adm2\support (Windows) or from the $DLC/src/adm2/support directory to src/adm2/support (UNIX) under your working directory, then modify the copy as needed.

Alternatively, you can either modify the original visuald.w instance properties dialog box in the %DLC%\src\adm2\support (Windows) or $DLC/src/adm2/support (UNIX) directory or create a completely new instance properties dialog box that includes support for the new property (as well as all other properties required by the class).

Regardless of which technique you use, you must be sure that the instance property dialog box filename matches the name that you specified in the custom instance definition file in your working directory. (See Step 5.)

Enable the new super procedure file by moving the .r file from the src\adm2 directory under your working directory into the adm2 directory under your working directory.
Note: If you do not move the .r file into the adm2 directory under your working directory, you will not be able to use the new super procedure.

The customized class, with its new property, is now ready for use. Before you work with it, you should restart the AppBuilder to re-establish the super procedure stack.